TypeScript Yapılandırması: Kapsamlı bir tsconfig.json Rehberi

JavaScript'in bir üst kümesi olan TypeScript, web geliştirmenin dinamik dünyasına statik tipleme getirir. İyi yapılandırılmış bir tsconfig.json dosyası, TypeScript'in tüm gücünden yararlanmak için çok önemlidir. Bu kılavuz, temel derleyici seçeneklerini, proje kurulumunu ve gelişmiş yapılandırmaları kapsayan tsconfig.json hakkında kapsamlı bir genel bakış sunar.

tsconfig.json Nedir?

tsconfig.json dosyası, bir TypeScript projesi için derleyici seçeneklerini belirten bir yapılandırma dosyasıdır. TypeScript derleyicisine TypeScript kodunu JavaScript'e nasıl dönüştüreceğini söyler. Bu dosya, projenin yapısını tanımlamak, derleme kurallarını belirlemek ve geliştirme ekibi ister tek bir ofiste bulunsun ister birden çok kıtaya dağılmış olsun, ekip genelinde tutarlılığı sağlamak için gereklidir.

Bir tsconfig.json Dosyası Oluşturma

Bir tsconfig.json dosyası oluşturmak için terminalde projenizin kök dizinine gidin ve aşağıdaki komutu çalıştırın:

            tsc --init
            

              
                Copy
              
            
          

Bu komut, sık kullanılan derleyici seçenekleriyle temel bir tsconfig.json dosyası oluşturur. Daha sonra dosyayı projenizin özel gereksinimlerine uyacak şekilde özelleştirebilirsiniz. Tipik bir tsconfig.json, compilerOptions, include ve exclude gibi seçenekleri içerecektir.

Temel Derleyici Seçenekleri

compilerOptions bölümü, tsconfig.json dosyasının kalbidir. TypeScript derleyicisinin davranışını kontrol eden çok çeşitli seçenekler içerir. İşte en önemli derleyici seçeneklerinden bazıları:

target

target seçeneği, oluşturulan JavaScript kodu için ECMAScript hedef sürümünü belirtir. Yaygın değerler arasında ES5, ES6 (ES2015), ES2016, ES2017, ES2018, ES2019, ES2020, ES2021, ES2022, ESNext bulunur. Doğru hedefi seçmek, tarayıcılar veya Node.js sürümleri gibi hedeflenen çalışma ortamıyla uyumluluğu sağlamak için çok önemlidir.

Örnek:

            {
  "compilerOptions": {
    "target": "ES2020"
  }
}
            

              
                Copy
              
            
          

module

module seçeneği, modül kodu oluşturma stilini belirtir. Yaygın değerler arasında CommonJS, AMD, System, UMD, ES6 (ES2015), ES2020 ve ESNext bulunur. Modül sistemi seçimi, hedef ortama ve kullanılan modül paketleyiciye (ör. Webpack, Rollup, Parcel) bağlıdır. Node.js için genellikle CommonJS kullanılırken, modern web uygulamaları için bir modül paketleyici ile ES6 veya ESNext tercih edilir. ESNext kullanmak, geliştiricilerin en son özelliklerden ve optimizasyonlardan yararlanmasına olanak tanırken, son modül formatını işlemek için paketleyiciye güvenir.

Örnek:

            {
  "compilerOptions": {
    "module": "ESNext"
  }
}
            

              
                Copy
              
            
          

lib

lib seçeneği, derlemeye dahil edilecek kütüphane dosyalarının bir listesini belirtir. Bu kütüphane dosyaları, yerleşik JavaScript API'leri ve tarayıcı API'leri için tür tanımları sağlar. Yaygın değerler arasında ES5, ES6, ES2015, ES2016, ES2017, ES2018, ES2019, ES2020, ES2021, ES2022, ESNext, DOM, WebWorker, ScriptHost, ES2015.Core, ES2015.Collection, ES2015.Iterable, ES2015.Promise, ES2015.Proxy, ES2015.Reflect, ES2015.Generator, ES2015.Symbol, ES2015.Symbol.WellKnown, ES2016.Array.Include, ES2017.object, ES2017.Intl, ES2017.SharedMemory, ES2017.String, ES2017.TypedArrays, ES2018.Intl, ES2018.Promise, ES2018.RegExp, ES2019.Array, ES2019.Object, ES2019.String, ES2019.Symbol, ES2020.BigInt, ES2020.Promise, ES2020.String, ES2020.Symbol.WellKnown, ES2021.Promise, ES2021.String, ES2021.WeakRef, ES2022.Error, ES2022.Object, ES2022.String ve çok daha fazlası bulunur. Uygun kütüphaneleri seçmek, TypeScript derleyicisinin hedef ortam için gerekli tür bilgisine sahip olmasını sağlar. DOM kütüphanesini kullanmak, projenin tarayıcıya özgü API'leri kullanan kodu tür hataları olmadan derlemesine olanak tanır.

Örnek:

            {
  "compilerOptions": {
    "lib": ["ES2020", "DOM"]
  }
}
            

              
                Copy
              
            
          

allowJs

allowJs seçeneği, TypeScript derleyicisinin JavaScript dosyalarını TypeScript dosyalarıyla birlikte derlemesine izin verir. Bu, mevcut JavaScript projelerini aşamalı olarak TypeScript'e taşımak için kullanışlıdır. Bunu true olarak ayarlamak, derleyicinin .js dosyalarını işlemesini sağlayarak bir proje içinde TypeScript'in kademeli olarak benimsenmesine olanak tanır.

Örnek:

            {
  "compilerOptions": {
    "allowJs": true
  }
}
            

              
                Copy
              
            
          

jsx

jsx seçeneği, JSX sözdiziminin nasıl ele alınacağını belirtir. Yaygın değerler arasında preserve, react, react-native ve react-jsx bulunur. preserve çıktıda JSX sözdizimini korurken, react JSX'i React.createElement çağrılarına dönüştürür. react-jsx, React 17'de tanıtılan ve React'i içe aktarmayı gerektirmeyen yeni JSX dönüşümünü kullanır. Doğru JSX seçeneğini seçmek, React veya diğer JSX tabanlı kütüphaneleri kullanan projeler için çok önemlidir.

Örnek:

            {
  "compilerOptions": {
    "jsx": "react-jsx"
  }
}
            

              
                Copy
              
            
          

declaration

declaration seçeneği, her TypeScript dosyası için karşılık gelen .d.ts bildirim dosyaları oluşturur. Bildirim dosyaları tür bilgilerini içerir ve derlenmiş kodu kullanmak için diğer TypeScript projeleri tarafından kullanılır. Bildirim dosyaları oluşturmak, yeniden kullanılabilir kütüphaneler ve modüller oluşturmak için gereklidir. Bu dosyalar, diğer TypeScript projelerinin, orijinal kaynak kodunu derlemeye gerek kalmadan kütüphane tarafından sunulan türleri ve arayüzleri anlamasına olanak tanır.

Örnek:

            {
  "compilerOptions": {
    "declaration": true
  }
}
            

              
                Copy
              
            
          

sourceMap

sourceMap seçeneği, oluşturulan JavaScript kodunu orijinal TypeScript koduna geri eşleyen kaynak harita dosyaları oluşturur. Kaynak haritaları, tarayıcılarda ve diğer ortamlarda TypeScript kodunda hata ayıklamak için gereklidir. JavaScript kodunda bir hata oluştuğunda, kaynak haritası geliştiricinin hata ayıklayıcıda karşılık gelen TypeScript kodunu görmesini sağlayarak sorunu tanımlamayı ve düzeltmeyi kolaylaştırır.

Örnek:

            {
  "compilerOptions": {
    "sourceMap": true
  }
}
            

              
                Copy
              
            
          

outDir

outDir seçeneği, oluşturulan JavaScript dosyaları için çıktı dizinini belirtir. Bu seçenek, kaynak kodu derlenmiş koddan ayırarak projenin derleme çıktısını organize etmeye yardımcı olur. Bir outDir kullanmak, derleme sürecini yönetmeyi ve uygulamayı dağıtmayı kolaylaştırır.

Örnek:

            {
  "compilerOptions": {
    "outDir": "dist"
  }
}
            

              
                Copy
              
            
          

rootDir

rootDir seçeneği, TypeScript projesinin kök dizinini belirtir. Derleyici, bu dizini modül adlarını çözümlemek için temel olarak kullanır. Bu seçenek, özellikle karmaşık bir dizin yapısına sahip projeler için önemlidir. rootDir'i doğru şekilde ayarlamak, derleyicinin gerekli tüm modülleri ve bağımlılıkları bulabilmesini sağlar.

Örnek:

            {
  "compilerOptions": {
    "rootDir": "src"
  }
}
            

              
                Copy
              
            
          

strict

strict seçeneği, tüm katı tür denetimi seçeneklerini etkinleştirir. Bu, geliştirme sürecinin başlarında olası hataları yakalamaya yardımcı olduğu için yeni TypeScript projeleri için şiddetle tavsiye edilir. Katı modu etkinleştirmek, daha katı tür denetimi kurallarını zorlayarak daha sağlam ve sürdürülebilir koda yol açar. Tüm yeni TypeScript projelerinde katı modu etkinleştirmek en iyi uygulamadır.

Örnek:

            {
  "compilerOptions": {
    "strict": true
  }
}
            

              
                Copy
              
            
          

esModuleInterop

esModuleInterop seçeneği, CommonJS ve ES modülleri arasında birlikte çalışabilirliği sağlar. Bu, her iki modül türünü de kullanan projeler için önemlidir. esModuleInterop etkinleştirildiğinde, TypeScript CommonJS ve ES modülleri arasındaki farkları otomatik olarak ele alarak iki sistem arasında modülleri içe ve dışa aktarmayı kolaylaştırır. Bu seçenek, farklı modül sistemleri kullanabilen üçüncü taraf kütüphanelerle çalışırken özellikle kullanışlıdır.

Örnek:

            {
  "compilerOptions": {
    "esModuleInterop": true
  }
}
            

              
                Copy
              
            
          

moduleResolution

moduleResolution seçeneği, TypeScript'in modül içe aktarmalarını nasıl çözümlediğini belirtir. Yaygın değerler arasında Node ve Classic bulunur. Node modül çözümleme stratejisi varsayılandır ve Node.js modül çözümleme algoritmasına dayanır. Classic modül çözümleme stratejisi daha eskidir ve daha az kullanılır. Node modül çözümleme stratejisini kullanmak, TypeScript'in bir Node.js ortamında modül içe aktarmalarını doğru bir şekilde çözümleyebilmesini sağlar.

Örnek:

            {
  "compilerOptions": {
    "moduleResolution": "Node"
  }
}
            

              
                Copy
              
            
          

baseUrl ve paths

baseUrl ve paths seçenekleri, göreceli olmayan modül içe aktarmaları için modül çözümlemesini yapılandırmak için kullanılır. baseUrl seçeneği, göreceli olmayan modül adlarını çözümlemek için temel dizini belirtir. paths seçeneği, modül adlarını dosya sistemindeki belirli konumlara eşlemenize olanak tanır. Bu seçenekler, özellikle karmaşık bir dizin yapısına sahip projeler ve modül içe aktarmalarını basitleştirmek için kullanışlıdır. baseUrl ve paths kullanmak, kodu daha okunabilir ve sürdürülebilir hale getirebilir.

Örnek:

            {
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@components/*": ["src/components/*"],
      "@utils/*": ["src/utils/*"]
    }
  }
}
            

              
                Copy
              
            
          

Include ve Exclude Seçenekleri

include ve exclude seçenekleri, derlemeye hangi dosyaların dahil edileceğini ve hangi dosyaların hariç tutulacağını belirtir. Bu seçenekler, dosya adlarını eşleştirmek için glob desenleri kullanır. include ve exclude kullanmak, TypeScript derleyicisi tarafından hangi dosyaların işleneceğini kontrol etmenize, derleme performansını artırmanıza ve hataları azaltmanıza olanak tanır. Derlemeye dahil edilecek dosyaları açıkça belirtmek en iyi uygulamadır.

Örnek:

            {
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}
            

              
                Copy
              
            
          

Extends Seçeneği

extends seçeneği, başka bir tsconfig.json dosyasından derleyici seçeneklerini miras almanıza olanak tanır. Bu, birden çok proje arasında ortak yapılandırma ayarlarını paylaşmak veya temel yapılandırmalar oluşturmak için kullanışlıdır. extends seçeneğini kullanmak, kodun yeniden kullanımını teşvik eder ve tekrarı azaltır. Temel yapılandırmalar oluşturmak ve bunları bireysel projelerde genişletmek en iyi uygulamadır.

Örnek:

            {
  "extends": "./tsconfig.base.json",
  "compilerOptions": {
    "jsx": "react-jsx"
  },
  "include": ["src/**/*"]
}
            

              
                Copy
              
            
          

Gelişmiş Yapılandırmalar

Temel derleyici seçeneklerinin ötesinde, tsconfig.json özel senaryolar için gelişmiş yapılandırmaları destekler.

Artımlı Derleme (Incremental Compilation)

Büyük projeler için artımlı derleme, derleme sürelerini önemli ölçüde iyileştirebilir. TypeScript, önceki derlemelerin sonuçlarını önbelleğe alabilir ve yalnızca değişen dosyaları yeniden derleyebilir. Artımlı derlemeyi etkinleştirmek, büyük projeler için derleme sürelerini önemli ölçüde azaltabilir. Bu, özellikle çok sayıda dosya ve bağımlılığı olan projeler için önemlidir.

            {
  "compilerOptions": {
    "incremental": true,
    "tsBuildInfoFile": ".tsbuildinfo"
  }
}
            

              
                Copy
              
            
          

Proje Referansları (Project References)

Proje referansları, büyük TypeScript projelerini daha küçük, bağımsız modüllere ayırmanıza olanak tanır. Bu, derleme sürelerini ve kod organizasyonunu iyileştirebilir. Proje referanslarını kullanmak, büyük projeleri daha yönetilebilir ve bakımı daha kolay hale getirebilir. Büyük, karmaşık projeler için proje referanslarını kullanmak en iyi uygulamadır.

            {
  "compilerOptions": {
    "composite": true
  },
  "references": [
    { "path": "./module1" },
    { "path": "./module2" }
  ]
}
            

              
                Copy
              
            
          

Özel Tür Tanımları (Custom Type Definitions)

Bazen, sahip olmayan JavaScript kütüphaneleri için tür tanımları sağlamanız gerekebilir. Bu kütüphaneler için türleri tanımlamak üzere özel .d.ts dosyaları oluşturabilirsiniz. Özel tür tanımları oluşturmak, TypeScript kodunuzda tür güvenliğinden ödün vermeden JavaScript kütüphanelerini kullanmanıza olanak tanır. Bu, özellikle eski JavaScript koduyla veya kendi tür tanımlarını sağlamayan kütüphanelerle çalışırken kullanışlıdır.

            // custom.d.ts
declare module 'my-library' {
  export function doSomething(x: number): string;
}
            

              
                Copy
              
            
          

En İyi Uygulamalar

• Katı Modu Kullanın (Use Strict Mode): Gelişmiş tür denetimi için strict seçeneğini etkinleştirin.
• Hedefi Belirtin (Specify Target): Çalışma ortamınız için uygun target sürümünü seçin.
• Çıktıyı Düzenleyin (Organize Output): Kaynak kodu derlenmiş koddan ayırmak için outDir kullanın.
• Bağımlılıkları Yönetin (Manage Dependencies): Hangi dosyaların derleneceğini kontrol etmek için include ve exclude kullanın.
• Extends'ten Yararlanın (Leverage Extends): extends seçeneğiyle ortak yapılandırma ayarlarını paylaşın.
• Yapılandırmayı Sürüm Kontrolüne Ekleyin: Geliştirici ortamları ve CI/CD işlem hatları arasında tutarlılığı korumak için `tsconfig.json` dosyasını git'e commit'leyin.

Sık Karşılaşılan Sorunları Giderme

tsconfig.json dosyasını yapılandırmak bazen zor olabilir. İşte bazı yaygın sorunlar ve çözümleri:

Modül Çözümleme Sorunları

Modül çözümleme hatalarıyla karşılaşırsanız, moduleResolution seçeneğinin doğru yapılandırıldığından ve baseUrl ile paths seçeneklerinin düzgün ayarlandığından emin olun. paths seçeneğinde belirtilen yolları doğru olduklarından emin olmak için iki kez kontrol edin. Gerekli tüm modüllerin node_modules dizininde yüklü olduğunu doğrulayın.

Tür Hataları

Tür tanımları yanlışsa veya eksikse tür hataları oluşabilir. Kullandığınız tüm kütüphaneler için doğru tür tanımlarının yüklü olduğundan emin olun. Tür tanımları olmayan bir JavaScript kütüphanesi kullanıyorsanız, özel tür tanımları oluşturmayı düşünün.

Derleme Hataları

TypeScript kodunuzda sözdizimi hataları veya tür hataları varsa derleme hataları oluşabilir. Hata mesajlarını dikkatlice inceleyin ve herhangi bir sözdizimi veya tür hatasını düzeltin. Kodunuzun TypeScript kodlama kurallarına uyduğundan emin olun.

Sonuç

İyi yapılandırılmış bir tsconfig.json dosyası, başarılı bir TypeScript projesi için esastır. Temel derleyici seçeneklerini ve gelişmiş yapılandırmaları anlayarak geliştirme iş akışınızı optimize edebilir, kod kalitesini artırabilir ve hedef ortamla uyumluluğu sağlayabilirsiniz. tsconfig.json'u doğru bir şekilde yapılandırmak için zaman ayırmak, hataları azaltarak, sürdürülebilirliği artırarak ve derleme sürecini kolaylaştırarak uzun vadede karşılığını verecektir. Bu, daha verimli ve güvenilir yazılım geliştirmeyle sonuçlanır. Burada sağlanan bilgiler evrensel olarak uygulanabilir olacak şekilde tasarlanmıştır ve TypeScript ile yeni bir projeye başlamak için sağlam bir temel sağlamalıdır.

Mevcut tüm derleyici seçeneklerinin en güncel bilgileri ve ayrıntılı açıklamaları için resmi TypeScript belgelerine başvurmayı unutmayın. TypeScript belgeleri, TypeScript yapılandırmasının inceliklerini anlamak için değerli bir kaynaktır.